Tricks of the Mac Game Programming Gurus/TricksOfTheMacGameProgrammingGurus.iso/Information/CSMP Digest/volume 1/csmp-v1-121.txt

Text File | 1994-12-08 | 47.9 KB | 1,192 lines | [TEXT/R*ch]

C.S.M.P. Digest             Mon, 22 Jun 92       Volume 1 : Issue 121

Today's Topics:

    In Search Of QuickTime
    Can you disable the FKEY3 resource?
    John Calhoun's Glypha3 source
    Anyone used XVT (esp. XVT++)?
    FOR SALE: TMON Professional
    Determining if user has a printer selected ???
    Yerk 3.62 available
    Icon Families and Icon Suites


The Comp.Sys.Mac.Programmer Digest is moderated by Michael A. Kelly.

These digests are available (by using FTP, account anonymous, your email
address as password) in the pub/mac/csmp-digest directory on ftp.cs.uoregon.
edu.  This is also the home of the comp.sys.mac.programmer Frequently Asked
Questions list.  The last several issues of the digest are available from
sumex-aim.stanford.edu as well.

These digests are also available via email.  Just send a note saying that you
want to be on the digest mailing list to [e-mail], and you will
automatically receive each new digest as it is created.

The digest is a collection of articles from the internet newsgroup comp.sys.
mac.programmer.  It is designed for people who read c.s.m.p. semi-regularly
and want an archive of the discussions.  If you don't know what a newsgroup
is, you probably don't have access to it.  Ask your systems administrator(s)
for details.  (This means you can't post questions to the digest.)

The articles in these digests are taken directly from comp.sys.mac.programmer.
They are not edited; all articles included in this digest are in their original
posted form.  The only articles that are -not- included in these digests are
those which didn't receive any replies (except those that give information
rather than ask a question).  All replies to each article are concatenated
onto the original article in the order in which they were received.  Article
threads are not added to the digests until the last article added to the
thread is at least one month old (this is to ensure that the thread is dead
before adding it to the digests).

Send administrative mail to [e-mail].

-------------------------------------------------------

From: [e-mail] (Bruce Henderson)
Subject: In Search Of QuickTime
Date: 19 May 92 01:17:12 GMT
Organization: Banzai Research Institute

Where can I get the File Format for the QuickTime file(s) type(s)?  If you know
or have it, please E-Mail me because I don't read this group regularly.

Thanks

Bruce Henderson
[e-mail]

+++++++++++++++++++++++++++

From: [e-mail] (Don Parsons)
Date: 21 May 92 01:14:09 GMT
Organization: Apple Computer, Inc.

In article <[e-mail]>, [e-mail] (Bruce Henderson) writes:
>
> Where can I get the File Format for the QuickTime file(s) type(s)?  If you know
> or have it, please E-Mail me because I don't read this group regularly.
>
> Thanks
>
> Bruce Henderson
> [e-mail]


The information that you want is in a package that is available through
the Apple Programmers and Developers Assn (APDA). It is called the
QuickTime Developer Kit. It includes the written documentation and a CD-ROM.
The CD-ROM has the QT software, utilities, samples, header/include files, etc.
There is also a package called the Quicktime Movie Exchange Toolkit, this
has information and resources for implementing QuickTime file format support
on other platforms.

Specific information you will need is as follows:

R0147LLA     Quicktime Developer Kit v.1.0                         $195.00
R0190LLA    *Quicktime Movie Exchange Toolkit                       $79.00


HOW TO ORDER
************

APDA offers convenient worldwide access to over 400 development tools,
resources, training products and information for anyone interested in
developing applications on Apple platforms.

LIST OF AVAILABLE APDA PRODUCTS
Customers can contact APDA for a complimentary copy of the APDA Tools Catalog
or view an APDA product list on AppleLink.

ORDERING FORMS
Ordering forms are available in the APDA Tools Catalog or on AppleLink.

If you are interested in purchasing beta (product that has not been finalized),
a completed and signed APDA Terms & Conditions form, found in the APDA Tools
Catalog, must be on file or accompany an order which includes a non Class 1
product.  This form need only be completed once, as it will remain current in
our files.  Non Class 1 products are starred in the on-line price lists.
*See the file "APDA Terms & Conditions".

International customers must have a letter of assurance on file before ordering
products.  *See the "Forms for International Customers" file.

ORDERING FORMATS
You can order APDA products by electronic mail, regular mail, or by telephone.
Note: Our customer service representatives cannot provide technical support.

% Electronic Mail
Orders can also be placed via the following services and electronic mail
addresses listed below.  Orders are downloaded daily.

AppleLink: APDA
MacNet: APDA
GEnie: A.DEVELOPER3
MCI: POSTROM
CompuServe: 76666,2405
Internet: [e-mail]

% Mail
Send APDA orders or inquiries to:
APDA
Apple Computer, Inc.
20525 Mariani Avenue, M/S: 33G
Cupertino, CA  95014-6299

% Phone
The following numbers are available for APDA product phone orders:

U.S.                    1-800-282-2732
Canada                  1-800-637-0029
International           1-408-562-3910
FAX                     1-408-562-3971
TELEX                   171-576

The phone lines are staffed Monday through Friday, 7:00 a.m. to 5:00 p.m.,
Pacific Standard Time. After hour orders can be placed on our recording
machine.


PAYMENT METHODS
APDA accepts MasterCard, VISA, American Express, or AppleCredit cards. Please
be sure to include your card's expiration date when ordering. We also
accept checks (on U.S. banks, in U.S. dollars).

We accept purchase orders with a minimum of $50 from U.S. corporations,
agencies, or schools only. APDA must receive an original hard-copy P.O. before
releasing any orders. All authorized individuals who can charge to the P.O.
should be listed for your protection.
*See the "Purchase Order Terms & Conditions" file for further information.



SHIPPING & HANDLING
U.S. Destinations: There is now a choice of delivery methods: Surface (UPS
Ground), Airborne, or Overnight Express (second day may be required).
Additionally, we will use First Class U.S. Mail for deliveries to all APOs,
FPOs, and PO Boxes. Your shipping charge is based on the table below. On mail
orders please remember to indicate which shipping method you prefer, or we will
default to surface. Surface delivery can take from 5-7 working days for
coast-to-coast.

Shipping and Handling for U.S. Orders

Product Order $$          Surface        Air

   $1-$100                  $3           $8
   $101-$200                $5           $15
   $201-$400                $8           $25
   $401-$600                $11          $35
   $601-$1,000              $15          $60
   over $1,000              $25          $100

International Destinations: The standard shipping method for international
orders is air express via TNT or Federal Express (Canada only). Please allow
24-48 hours for your order to clear customs. Companies or groups using the
services of a customs broker should provide the broker's name and telephone
number with the order. Large orders may qualify for Rdeferred air service at
substantially lower rates. Total time from departure through customs is 5-7
working days. Please request information about this service from our customer
service staff.

If you have ordered E.T.O. or APDA Developer Mailing, additional shipping
charges apply.  E.T.O.: U.S.-$15, Canada-$40, other countries-$100.  APDA
Technical Information mailing: U.S.-$30, Canada-$80, other countries-$200.
Please add these amounts to the above shipping charges on the order form.


POLICIES
% Returns
APDA accepts returns at any time, for any reason.  Please reference the back of
your packing slip for details.  You will need to include the packing slip with
the returned merchandise.  At your option, we will gladly replace your shipment
at no charge or issue a refund against your original payment method.

% Upgrades
Upgrade policies vary from product to product.  While the purchase of some
products guarantees an upgrade to the next version, the purchase of others
might not have that same guarantee.

% Purchase Protection
To protect your investment in development tools, we offer 30-day purchase
protection for all Apple-labeled products.  If within 30 days of the date you
purchase a product, we begin taking orders for a new version of that product,
you will automatically receive the update version at no additional charge.


Developer Support
Developer Services
APDA - Tools for Developers
Price Lists & Ordering Information
9-10-91




---------------------------

From: filibert@vista (Daniel Filiberti)
Subject: Can you disable the FKEY3 resource?
Date: 14 May 92 18:44:08 GMT
Organization: Oregon Health Sciences University

Hi Everyone!

Is it possible to disable the FKEY 3 system resource that
allows snapshots of the screen in System 7?

Also, can bg processes be disabled by some other means
other than using the parameters to WaitNextEvent?

Thanks,

Daniel

- --
************************************************************
Motto for a monitor, "It's better to burn out, than to fade
 away..."  [8?)}
************************************************************

Daniel Filiberti
[e-mail]

+++++++++++++++++++++++++++

From: [e-mail] (Pete Gontier)
Date: 20 May 92 17:17:29 GMT

In <[e-mail]> filibert@vista (Daniel Filiberti) writes:
>Is it possible to disable the FKEY 3 system resource that
>allows snapshots of the screen in System 7?

Low memory: ScrDmpEnb at 0x02F8 is a boolean byte. Beware, it really
disables *all* FKEYs, not just FKEY 3. If you want to disable FKEY 3
permanently, chop it out of the System file. But you would have
thought of that already had it been your aim.

>Also, can bg processes be disabled by some other means
>other than using the parameters to WaitNextEvent?

Too vague. Try again.
- --
 Pete Gontier // EC Technology // [e-mail]

+++++++++++++++++++++++++++

From: [e-mail] (Matt Mora)
Date: 19 May 92 17:01:03 GMT
Organization: SRI International, Menlo Park, California

In article <[e-mail]> [e-mail] writes:
>Hi Everyone!
>
>Is it possible to disable the FKEY 3 system resource that
>allows snapshots of the screen in System 7?

If you want to do it in an application just add an fkey resource
of id 3 in your app that does nothing. Also I think there is a low
memory global you can set to not launch any fkeys. I think
it was used by fkeys so that the user does not re-enter the
same fkey or launch two at once. I wish I could remember the name
of the global. Maybe I should have asked this question at the
"Stump the experts" session at the WWDC. :-)

>Also, can bg processes be disabled by some other means
>other than using the parameters to WaitNextEvent?

Don't know about disabling them. You can kill them or wake them up.
You might be able to hide them (though its not documented).
Look at the Process manager chapter in IM vol 6.


Matt



- --
___________________________________________________________
Matthew Mora                |   my Mac  [e-mail]
SRI International           |  my unix  [e-mail]
___________________________________________________________

+++++++++++++++++++++++++++

From: [e-mail] (Pete Gontier)
Date: 21 May 92 05:32:15 GMT

In <[e-mail]> [e-mail] (Matt Mora) writes:

>of the global. Maybe I should have asked this question at the
>"Stump the experts" session at the WWDC. :-)

Woo woo! I'm an expert! Look ma, I'm an expert! I'm an expert! Woo woo!
- --
 Pete Gontier // EC Technology // [e-mail]

---------------------------

From: [e-mail] (Sterling Chipperfield)
Subject: John Calhoun's Glypha3 source
Date: Sat, 16 May 92 22:7:54 EST
Organization: Argentic BBS [Toronto, Ontario, Canada]

I tried to compile this source with THINK Pascal 4.0 updated to 4.0.1
and while compiling this routine I got a Type Incompatibility error:

 procedure CheckTheKeyboard;
  var
   keyState: KeyMap;
 begin
  keyStillDown := FALSE;
  GetKeys(keyState);
  if (keyState[0] = 16777216) or (keyState[0] = 33554432) then
   keyStillDown := TRUE
  else
   begin
    if ((keyState[1] > 131071) and (keyState[1] < 131075)) then
     keyStillDown := TRUE
    else if ((keyState[1] > -2147483649) and (keyState[1] < -2147483645))
then
     keyStillDown := TRUE;
   end;
 end;

The error was on the 7th line (beginning with if (keyState[0]....)
When I checked my IM I on page 260 it says that:

TYPE KeyMap = PACKED ARRAY[0..127] OF BOOLEAN;

I have seen the compiled game Glypha, so I know it compiles on John's
machine, but why? or why not on my machine?

        _____________________        ________________________
        Sterling Chipperfield        Toronto, Ontario, Canada
         [e-mail]            V: 1-416-269-5335
           [e-mail]             D: 1-416-265-4025
        _____________________        ________________________

+++++++++++++++++++++++++++

From: [e-mail] (Matt Mora)
Date: 19 May 92 17:11:27 GMT
Organization: SRI International, Menlo Park, California

In article <[e-mail]> [e-mail] (Sterling Chipperfield) writes:
>I tried to compile this source with THINK Pascal 4.0 updated to 4.0.1
>and while compiling this routine I got a Type Incompatibility error:

> procedure CheckTheKeyboard;
>  var
>   keyState: KeyMap;
> begin
>  keyStillDown := FALSE;
>  GetKeys(keyState);
>  if (keyState[0] = 16777216) or (keyState[0] = 33554432) then

>The error was on the 7th line (beginning with if (keyState[0]....)
>When I checked my IM I on page 260 it says that:

>TYPE KeyMap = PACKED ARRAY[0..127] OF BOOLEAN;

In the old version of think pascal I believe define the Keymap as
PACKED ARRAY[0..3] OF LONGINT, hense John's use of longints to test
the keymap. Think Pascal 4.0 now correctly defines teh keymap as array
of booleans. So you nee to test the specific array element for true
or false.









Matt

- --
___________________________________________________________
Matthew Mora                |   my Mac  [e-mail]
SRI International           |  my unix  [e-mail]
___________________________________________________________

---------------------------

From: [e-mail] (Captain Nerd)
Subject: Anyone used XVT (esp. XVT++)?
Date: 19 May 92 15:39:08 GMT
Organization: Express Access Online Communications, Greenbelt, Maryland USA


    Hi!

    The company I work for is looking to make a portable product that
can work on PCs with Windows, workstations, and possibly Macintoshes (if I
get my way 8^).  We want to use C++, and we have the XVT propaganda sheets 8^),
but I'd like to hear from anyone who has used XVT >>in a production
environment<<.  If you have also used XVT++, their C++ library, I'd like to
hear from you.  I don't want to know >>what<< you're doing with it, I just
want to know what kind of problems, peculiarities, good things, etc. you've
had with it.  Please e-mail me to save bandwidth.

    Thanks in advance!




- --
| Internet: [e-mail] |  "From the hard-scrabble back streets, that
| [e-mail]    |  part of town called 'OOP Alley,' comes a
champion for the Future, defender of overworked programmers everywhere,
and foe of all who call themselves 'Management!'  Captain Nerd!"

+++++++++++++++++++++++++++

From: [e-mail] (David Zeitler)
Organization: Smiths Industries
Date: Wed, 20 May 1992 11:58:47 GMT

In <[e-mail]> [e-mail] (Captain Nerd) writes:

>    Hi!

>    The company I work for is looking to make a portable product that
>can work on PCs with Windows, workstations, and possibly Macintoshes (if I
>get my way 8^).  We want to use C++, and we have the XVT propaganda sheets 8^),
>but I'd like to hear from anyone who has used XVT >>in a production
>environment<<.  If you have also used XVT++, their C++ library, I'd like to
>hear from you.  I don't want to know >>what<< you're doing with it, I just
>want to know what kind of problems, peculiarities, good things, etc. you've
>had with it.  Please e-mail me to save bandwidth.

>    Thanks in advance!

Please either post information, or email to me as well. I am also interested
in the real (as opposed to marketing hype) capabilities/value of XVT/XVT++.

- ---
Dave Zeitler                [e-mail]
Smith's Industries            Ph: [phone]
Aerospace & Defense Systems Inc.    Fax: [phone]
4141 Eastern Ave, SE
Grand Rapids, MI 49518-8727

+++++++++++++++++++++++++++

From: [e-mail] (Matt Weiser)
Organization: Martin Marietta WIS
Date: Thu, 21 May 1992 20:32:48 GMT

In article <[e-mail]>, [e-mail] (Captain Nerd) writes:
>
>
>     Hi!
>
>     The company I work for is looking to make a portable product that
> can work on PCs with Windows, workstations, and possibly Macintoshes (if I
> get my way 8^).  We want to use C++, and we have the XVT propaganda sheets 8^),
> but I'd like to hear from anyone who has used XVT >>in a production
> environment<<.  If you have also used XVT++, their C++ library, I'd like to
> hear from you.  I don't want to know >>what<< you're doing with it, I just
> want to know what kind of problems, peculiarities, good things, etc. you've
> had with it.  Please e-mail me to save bandwidth.
>
>     Thanks in advance!

We have a development group of 7 who have been working with XVT and XVT++ for
about 2 years now.  We have had success implementing our software with it,
but it drives me crazy.  It does not allow you to do so many things Mac programs
do naturally.  Here are just a couple of the limitations I have personally run into:

No Regions
No CopyBits
Very few drawing commands (limits QuickDraw greatly!)
No ability to write resources (specifically STR's)
No GetMouse (you cannot just ask where the mouse is)
No Popup Buttons
Limited Patterns (no custom ones - only theirs)

It's basically the lowest common denominator between platforms.  You
loose all the neat Mac things you have come to love.  It does
a good job within its bounds, but don't try to cross them.

I'm not super impressed with XVT++.  We have decided to not renew
our licenses for it, choosing to go on our own.

Matt Weiser
[e-mail]







---------------------------

From: [e-mail] (David A. Carlton)
Subject: FOR SALE: TMON Professional
Date: 19 May 92 23:36:37 GMT
Organization: Sacramento Public Access Unix

I have an extra copy of TMON Professional still in the box which
never got used by one of my programmers. Original cost $249, I will
let it go for $200 and pay shipping. If you can find it for less
than tell me where and how and I will beat the cost by $50. You
WILL save at least that much!

- --
#############################################################
# Dave Carlton, Poly Micro Systems, N. Highlands, CA 95660  #
# [phone] [e-mail]                      #
#############################################################

+++++++++++++++++++++++++++

From: [e-mail]
Date: 20 May 92 10:16:26 PST
Organization: California State Polytechnic University, Pomona

In article <[e-mail]>, [e-mail] (David A. Carlton) writes:
> I have an extra copy of TMON Professional still in the box which
> never got used by one of my programmers. Original cost $249, I will
> let it go for $200 and pay shipping. If you can find it for less
> than tell me where and how and I will beat the cost by $50. You
> WILL save at least that much!
>
> --
> #############################################################
> # Dave Carlton, Poly Micro Systems, N. Highlands, CA 95660  #
> # [phone] [e-mail]                      #
> #############################################################

Is your version system 7 compatible.  If so I might be interested but not at $200.00  I can't really afford that.

Matt

---------------------------

From: [e-mail] (Juha Pirttil{)
Subject: Determining if user has a printer selected ???
Date: 20 May 92 07:43:01 GMT
Organization: Department of Physics, University of Oulu

Hi!

I have been wondering if there is a reliable way of determining
that user has selected a printer.
I have a program that cheks printer page size etc. when it
starts up. When testing the program my two friends succeeded
in having no printer selected. The program did not get the
pageSizes etc correctly and hung. Currently I check the
printRec^^.PRstl.wdev field. I think it should be 0 when
there is no printer selected but it seems that this is
not true if I have a LaserWriter selected. Sometimes
I get the alert which says that "You have no printer...."
and sometimes I do not get the alert. So, what method
would you use to determine if there is a printer selected ?


   Juha Pirttil{
   Department of Physics
   University of Oulu
   Finland

+++++++++++++++++++++++++++

From: [e-mail] (Marshall Clow)
Organization: Hewlett Packard San Diego Printer Division
Date: Wed, 20 May 1992 16:04:42 GMT

In article <[e-mail]>, Juha Pirttil{ <[e-mail]> writes:
> I have been wondering if there is a reliable way of determining
> that user has selected a printer.

How about checking to see if the printer manager calls ( like PrDefault )
return an error? ( PrError ).

This should determine if there is no printer driver selected.
The only way to determine ( in general, but methods exist for
AppleTalk printers ) if the user has selected
a printer that doesn't exist is to try to print to it.

Marshall Clow
[e-mail]


+++++++++++++++++++++++++++

From: [e-mail] (Lloyd Lim)
Date: 21 May 92 05:39:17 GMT
Organization: U.C. Davis - Department of Computer Science

In article <[e-mail]> [e-mail] (Juha Pirttil{) writes:
>
>I have been wondering if there is a reliable way of determining
>that user has selected a printer.

Just call PrError to check for an error immediately after you call PrOpen.
It works fine for me.  In fact, you're supposed to be calling PrError
after every Print Manager call (in the same way you're supposed to call
MemError and ResError for the Memory and Resource Managers).  It's never
too late to learn a habit like defensive programming.

+++
Lloyd Lim               Internet: [e-mail]
224 Lysle Leach Hall    America Online: LimUnltd
U.C. Davis              AppleLink: LimUnltd
Davis, CA  95616        CompuServe: 72647,660

---------------------------

Subject: Yerk 3.62 available
From: [e-mail] (Bob Loewenstein)
Date: Wed, 20 May 1992 14:48:46 GMT
Organization: University of Chicago, Astronomy and Astrophysics


Yerk 3.62 is now available for anonymous ftp at oddjob.uchicago.edu in
directory pub/Yerk.  While 3.60 ran on a Quadra, there was a finite
probability that it might not since there were a few places where code
was being modified. 3.62 fixes this so that I don't think this will
ever be a problem. Also A5 is handle better so that VBL tasks, Time
Manager, Serial Completion Routines, etc are handled much more nicely
for system 7 environments.  3.62 also makes it a bit easier to make
a standalone application with multiple CODE segments.

For those that aren't aware of Yerk -

Yerk is an object oriented language based on a Forth Kernel with some
major modifications.  It was originally known as Neon, developed and
sold as a product by Kriya Systems from 1985 to 1989. Several of us at
The University of Chicago have maintained Yerk since its demise as a
product. Because of the possible trademark conflict that Kriya
mentions, we picked the name Yerk, which is at least not an acronym
for anything, but rather stands for Yerkes Observatory, part of the
Department of Astronomy and Astrophysics at U of C.


MOPS 2.1 is also available at oddjob. MOPS is also a varient of NEON
and is made available by Michael Hore.


---------------------------

From: [e-mail] (Neal Trautman)
Subject: Icon Families and Icon Suites
Date: 20 May 92 14:45:37 GMT
Organization: Farallon Computing, Inc.

Hi All,

Tech Note #306, on the May Developer's CD, has the
full details on System 7 Finder Icon Families and
Icon Suites.

For those of you that don't have access to this
Tech Note, I have included it below.

Anyone care to gues what happens if you create
a menu with a title that is 5 bytes long, has
a CHR($01) as the second byte, and a handle
to an icon family as the next 4 bytes??

Enjoy...
Neal Trautman
Timbuktu Lead Software Engineer
Farallon Computing, Inc.
[e-mail]

==========
  #306:    Drawing Icons the System 7 Way

Revised by:    Jim Mensch                      May 1992
Written by:    Jim Mensch and David Collins    October 1991

This Technical Note describes how to utilize the built-in System 7 icon drawing
utility. Use this information to better conform to the System 7.0 visual human
interface.



Introduction

With the introduction of System 7.0 for the Macintosh, Apple has defined a new
look and feel for many screen elements that better utilize color. Among other
elements, the icons drawn by the Finder and other system components have been
redefined. While Apple has documented how to create this new look for most
elements, Apple has not documented how to draw the icons the way the Finder
does in System 7. This Technical Note discusses all the icon toolkits that the
Finder uses to draw and manipulate the icons on the screen. Two of the calls,
PlotIconID and PlotCIconHandle, are the ones you will probably use the most
since they deal with simply drawing single icons to the screen. Other places in
the Toolbox require that an icon family handle be passed to them to allow the
drawing of color icons. The toolkit provides calls that allow you to create,
draw, and manipulate these handles. What follows is a description of the new
icon data structures and the calls in the icon toolkit.

 The New 'ic' Type Resources

PlotIconID and PlotCIconHandle allow the use of standard CIcons as documented
in Inside Macintosh Volume V and the use of a new set of icon resources
utilized by the PlotIconID call. This new icon type is actually not a single
resource but a collection of many different icons into a family. Each member of
the family has a consistent resource ID and a resource type indicating what
type of icon data is stored in that particular resource. Currently Apple has
defined three sizes of icons and three different bit depths for each size. The
sizes are large (32x32 pixels), small (16x16 pixels), and mini (12x12 pixels),
and the bit depths are 1, 4, and 8. The actual resource types are defined as
follows:

Large1BitMask       =    'ICN#';
Large4BitData       =    'icl4';
Large8BitData       =    'icl8';
Small1BitMask       =    'ics#';
Small4BitData       =    'ics4';
Small8BitData       =    'ics8';
Mini1BitMask        =    'sicn';
Mini4BitData        =    'icm4';
Mini8BitData        =    'icm8';

The 1-bit-per-pixel member of each size also contains the mask data for all
icons of that size (yes, this means that all your icons of a certain size must
have the same mask). A 1-bit-per-pixel member must exist for each icon size you
want PlotIconID to use. The icon size to use is determined by the size of the
destination rectangle. If the destination rect is greater than 16 pixels on a
side then the large icon will be used. If the destination rect is 13P16 pixels
on both sides the small icon will be used. If the destination is 12 or less on
each side the mini icon will be used. The bit depth is determined by the device
of the grafPort you plot into at drawing time. Be sure that you always create a
color grafPort any time you want to use color icons.

 Icon Families (or Suites and Caches As the Tool Set Refers to Them)

An icon family is simply a collection of icon handles that contain up to one
image of each bit depth and size for a given icon. By using families, you
remove the need to determine which size or depth of icon to use when drawing
into a given rectangle. Several system routines can take an icon family handle
when an icon is requested (the Notification Manager for example) so that the
proper color icons can be used if available. An icon family can be fully
populated (every possible size or depth available) or it can have only those
icons that exist or are needed. In the case of a sparsely populated icon
family, if the proper icon is not available the icon tool set will pick an
appropriate substitute that will produce the best results.

An icon cache is a family that also has a ProcPtr and a refCon. The main
difference between a cache and a family is that the elements of the cacheUs
array are sparsely populated. When using an icon cache, the system either will
use the entry in the icon family portion of the cache, or if the desired
element is empty, it will call your procPtr and request the data for the icon.
The Proc has the following calling convention:

Function GetAnIcon(theType:ResType; yourDataPtr:Ptr):Handle;

This function should return either the icon data to be used to draw or NIL to
signify that this entry in the icon cache does not exist. Icon caches can be
used with all icon family calls and have a few extra calls used to manipulate
them.

Now that we know about the different data types letUs examine how to manipulate
the drawing:

 Drawing Modes or Transforms

In addition to being drawn in various sizes and bit depths, icons can be drawn
with different RModesS or transforms. Transforms are analogous to certain
Finder states for the icons. For example, the transform that you would use to
show an icon of a disk that has been ejected is ttOffline. Here is a list of
the current transforms that are available:

{ IconTransformType values }
ttNone                =    $0;
ttDisabled            =    $1;
ttOffline             =    $2;
ttOpen                =    $3;
ttSelected            =    $4000;
ttSelectedDisabled    =    (ttSelected + ttDisabled);
ttSelectedOffline     =    (ttSelected + ttOffline);
ttSelectedOpen        =    (ttSelected + ttOpen);

The actual appearance of the icon drawn by each transform type may vary with
future system software, so you should always try to use the transform that best
fits the state it represents in your application. In this way you will be
consistent with any possible future changes to the look and feel of regular
system icons. Note that the ttSelected transform can be added to any of the
other transform types. Additional transform types exist for displaying the icon
of a file inside your application that use the Finder label colors to color the
icon. To determine the proper label for a fileUs icon, you can check bits 1P3
of the fdFlags field in the fileUs Finder info (See the File Manager chapter in
Inside Macintosh Volume IV for more information). These bits contain a number
from 0 to 7. Simply add the corresponding ttLabel value to the transform that
you give the call. The label values are defined like this:

ttLabel0            =    $0000;
ttLabel1            =    $0100;
ttLabel2            =    $0200;
ttLabel3            =    $0300;
ttLabel4            =    $0400;
ttLabel5            =    $0500;
ttLabel6            =    $0600;
ttLabel7            =    $0700;

 Alignment

Most icons do not fully fill their rectangle, and it is sometimes necessary to
draw an icon relative to other data (like menu text). In these instances it
would be nice to be able to have the icon move in its rectangle so that it will
be at a predictable location in the destination rectangle. Therefore, when
drawing an icon you can pass one of these standard alignments in the alignment
parameter or you can add a vertical alignment to a horizontal alignment to
create a composite alignment value.

atNone              =    $0;
atVerticalCenter    =    $1;
atTop               =    $2;
atBottom            =    $3;
atHorizontalCenter  =    $4;
atLeft              =    $8;
atRight             =    $C;

 And Now (Drum Roll Please) the Calls and What to Pass

Now that we have defined every major data type we can think of, here is the
real meat of this Tech Note: the actual calls themselves. I am  providing only
the Pascal and C interfaces here since they do not appear in your current MPW
Interfaces folder. Disk copies of these can be found on AppleLink and on
current and future versions of the Developer CD Series  disc.
Icon Family Calls

Function NewIconSuite(var theSuite:Handle):OSErr;

This call returns an empty icon family handle with all members set to NIL.

Function AddIconToSuite(theIconData: Handle; theSuite:Handle;
theType:ResType):OSErr;

This call will add the data in theIconData into the suite at the location
reserved for theType of icon data. This call will replace any old data in that
slot without disposing of it, so you may want to call GetIconFromSuite to
obtain the old handle (if any) to dispose. This call will be used most often
with the NewIconSuite call to fill the empty family after itUs created.

Function GetIconFromSuite(Var theIconData:Handle; theSuite:Handle;
theType:ResType):OSErr;

This call will return a handle to the pixel data of the family member of
theSuite specified by theType. If you intend to dispose of this handle, be sure
to call AddIconToSuite with a NIL handle to zero out the family entry.

Function ForEachIconDo(theSuite: Handle; theSelector:Longint;
actionProc:procPtr; yourData: UNIV ptr):OSErr;

This routine will call your actionProc for each icon in the family specified by
theSelector and theSuite. TheSelector is a bit level flag that specifies which
family members to operate on; they can be added together to create composite
selectors that work on several different family members. The values for
theSelector are as follows:



    { IconSelectorValue masks }
svLarge1Bit           =    $00000001;
svLarge4Bit           =    $00000002;
svLarge8Bit           =    $00000004;
svSmall1Bit           =    $00000100;
svSmall4Bit           =    $00000200;
svSmall8Bit           =    $00000400;
svMini1Bit            =    $00010000;
svMini4Bit            =    $00020000;
svMini8Bit            =    $00040000;
svAllLargeData        =    $000000ff;
svAllSmallData        =    $0000ff00;
svAllMiniData         =    $00ff0000;
svAll1BitData         =    (svLarge1Bit + svSmall1Bit + svMini1Bit);
svAll4BitData         =    (svLarge4Bit + svSmall4Bit + svMini4Bit);
svAll8BitData         =    (svLarge8Bit + svSmall8Bit + svMini8Bit);
svAllAvailableData    =    $ffffffff;

The action procedure that gets called for each icon type selected for the
family is a Pascal type function with the following interface:

Function ActionProc(var theIconData:Handle; theType:ResType; yourDataPtr: UNIV
ptr):OSErr;

theIconData is passed by reference here so that your routine can modify the
contents of the suite directly. yourDataPtr is the value passed when you called
forEachIconDo; it allows you to easily communicate with your application. The
action procedure returns an OSErr; if any value other than noErr is returned,
forEachIconDo will stop processing immediately and return the error passed.
(Note: This implies that the icons selected may only be partially operated on.)
There is no guaranteed order in which the icons get operated on.

Function GetIconSuite(Var theSuite: Handle; theID:Integer;
theSelector:Longint):OSErr;

GetIconSuite will create a new icon family and then fill it with the icons with
the passed ID, of the indicated types in theSelector, from the current resource
chain. This is the call you will probably use most often to create an icon
family. Note: If you SetResLoad(False) before making this call, the suite will
be filled with unloaded resource handles.

Function PlotIconSuite(theRect:Rect; alignment:Integer; transform:Integer;
    theSuite:Handle):OSErr;

This call renders the proper icon image from the passed icon family based on
the bit depth of the display you are using and the rectangle that you have
passed. Alignment and transform are applied to the icon selected for drawing
and then the icon is plotted into the current grafPort. PlotIconSuite chooses
the appropriate icon based primarily on size; once the proper icon size is
determined (based on the destination rectangle) the present member of that size
with the deepest bit depth that the current device can use is selected. A size
category is considered present if the black and white member (with mask) is
present, ICN#, ics#, or icm#. PlotIconSuite can be used for both picture
accumulation and printing.

Function DisposeIconSuite(theSuite:Handle; disposeData:Boolean):OSErr;

This call disposes the icon family handle itself; in addition if disposeData is
true, any of the icon data handles that do not belong to a resource fork will
also be disposed.

Function SetSuiteLabel(theSuite: Handle; theLabel:Integer):OSErr;

This call allows you to specify a label that is used to draw an icon of this
suite when noLabel is specified in PlotIconSuite. This is used primarily when
you want to make sure that a family passed to a system routine gets drawn with
the proper label. The default label can be overridden by specifying a label in
PlotIconSuite.

Function GetSuiteLabel(theSuite:Handle; var theLabel:Integer):OSErr;

returns any label set with SetSuiteLabel previously.

Icon Cache Calls

In addition to the icon family calls above, icon caches have these additional
calls:
Function MakeIconCache(VAR theCache:Handle; GetAnIcon:ProcPtr;
                        yourDataPtr:Ptr):OSErr;

This call creates an empty icon cache similar to NewIconSuite, and associates
the additional icon loading proc and data value with the family.

Function LoadIconCache(theRect:Rect; alignment:Integer; transform:Integer;
    theSuite:Handle):OSErr;

This call allows you to preflight the loading of certain elements of your icon
cache. This is handy when you suspect that certain drawing operations will
occur at a time not convenient for you to load your icon data (for example,
when your resource fork might not be in open chain). LoadIconCache takes the
same parameters as PlotIconSuite and uses the same criterion to select the icon
to load. Be sure that the grafPort is set properly before you make this call
since it is part of the criterion for determining which icon to load.

The following four calls are provided to allow you to change the dataPtr and
procPtr associated with an icon cache:

Function GetCacheData(theCache:Handle; VAR yourDataPtr:Ptr):OSErr;
Function SetCacheData(theCache:Handle;     yourDataPtr:Ptr):OSErr;
Function GetCacheProc(theCache:Handle; VAR theProc:ProcPtr):OSErr;
Function SetCacheProc(theCache:Handle;     theProc:ProcPtr):OSErr;



Plotting Icons Not Part of a Suite

The following two calls are grouped because they are very similar. These
routines let you simply plot an icon to the screen without having to create an
icon suite. They are also good if you have a cicn instead of an icon family.

FUNCTION PlotIconID(TheRect: Rect; Align: Integer; Transform: Integer;
TheResID: INTEGER): OSErr;

FUNCTION PlotCIconHandle(TheRect: Rect; Align: Integer; transform: Integer;
TheCIcon: CIconHandle): OSErr;

TheRect is the destination rectangle to draw the indicated icon into.

Align is the alignment method to use if the icon does not exactly fit the
rectangle given. Pass zero for this value. See the next version of this Tech
Note for more information on alignment.

Transform indicated the desired appearance of the icon on the screen.

TheResID is the resource ID of the family of 'ic' type resources to use. If the
correct bit depth or size required is not defined, the closest-fitting one will
be used.

TheCIcon is a handle that you get to a standard QuickDraw color icon. Call
GetCIcon to load these and do not forget to dispose of it when you are done
(sometimes they can take up quite a bit of memory).

Both functions return an error code if all did not go well with the drawing, or
in the case of the PlotIconID call, if the indicated icon family could not be
used.

Miscellaneous Calls

Function GetLabelColor(labelNumber:Integer; var labelColor:RGBColor; VAR
LabelString:str255):OSErr;

This call returns the actual color and string used in the label menu of the
Finder and the labelUs Control Panel. This information is provided in case you
wish to include the label text or color when displaying a fileUs icon in your
application.

Function IconSuiteToRgn(theRgn: RgnHandle; iconRect:Rect Alignment:Integer;
iconSuite:Handle):OSErr;
Function IconIDToRgn(theRgn: RgnHandle; iconRect:Rect Alignment:Integer;
iconID:Integer):OSErr;

These routines will create a region from the mask of the icon selected by the
Rect and Alignment passed. This will allow you to do accurate hit testing and
outline dragging of an icon in your application. TheRgn handle must have been
previously allocated before you make this call.

Function RectInIconSuite(testRect:Rect; iconRect:Rect; Alignment:Integer;
IconSuite:Handle):Boolean;
Function RectInIconID(testRect:Rect; iconRect:Rect; Alignment:Integer;
IconID:Integer):Boolean;
Function PtInIconSuite(testPoint:Point; iconRect:Rect; Alignment:Integer;
IconSuite:Handle):Boolean;
Function PtInIconID(testPoint:Point; iconRect:Rect; Alignment:Integer;
IconID:Integer):Boolean;

These calls hit test the passed point or rect again the icon indicated. The
iconRect, alignment, and grafPort should be the same as when the icon was drawn
last. They return true if the point is in the icon mask, or if the rect
intersects the icon mask.

Glue for C and Pascal

Since the standard interface files do not contain the glue for these calls,  I
am going to include it here since Tech Notes sometimes get distributed in
electronic format and if all else fails you can copy and paste it.

{ Pascal Glue }
FUNCTION PlotIconID(theRect: Rect;align: Integer;transform: Integer;
    theResID: INTEGER): OSErr;    INLINE $303C, $0500, $ABC9;
FUNCTION NewIconSuite(VAR theIconSuite: Handle): OSErr;    INLINE $303C, $0207, $ABC9;
FUNCTION AddIconToSuite(theIconData: Handle;theSuite: Handle;theType: ResType): OSErr;
    INLINE $303C, $0608, $ABC9;
FUNCTION GetIconFromSuite(VAR theIconData: Handle;theSuite: Handle;theType: ResType): OSErr;
    INLINE $303C, $0609, $ABC9;
FUNCTION ForEachIconDo(theSuite: Handle;selector: Integer;action: ProcPtr;
    yourDataPtr: Ptr): OSErr;    INLINE $303C, $060A, $ABC9;
FUNCTION GetIconSuite(VAR theIconSuite: Handle;theResID: INTEGER;
    selector: Integer): OSErr;    INLINE $303C, $0501, $ABC9;
FUNCTION DisposeIconSuite(theIconSuite: Handle;disposeData: BOOLEAN): OSErr;
    INLINE $303C, $0302, $ABC9;
FUNCTION PlotIconSuite(theRect: Rect;align: Integer;transform: Integer;
    theIconSuite: Handle): OSErr;    INLINE $303C, $0603, $ABC9;
FUNCTION MakeIconCache(VAR theHandle: Handle;makeIcon: procPtr;
    yourDataPtr: UNIV Ptr): OSErr;    INLINE $303C, $0604, $ABC9;
FUNCTION LoadIconCache(theRect: Rect;align: Integer;transform: Integer;
    theIconCache: Handle): OSErr;    INLINE $303C, $0606, $ABC9;
FUNCTION GetLabel(labelNumber: INTEGER; VAR labelColor: RGBColor;
    VAR labelString: Str255): OSErr;    INLINE $303C, $050B, $ABC9;
FUNCTION PtInIconID(testPt: Point; iconRect: Rect; align: Integer;
     iconID: INTEGER): BOOLEAN;    INLINE $303C, $060D, $ABC9;
FUNCTION PtInIconSuite(testPt: Point; iconRect: Rect;align: Integer;
    theIconSuite: Handle): BOOLEAN;    INLINE $303C, $070E, $ABC9;
FUNCTION RectInIconID(testRect: Rect; iconRect: Rect;align: Integer;
    iconID: INTEGER): BOOLEAN;    INLINE $303C, $0610, $ABC9;
FUNCTION RectInIconSuite(testRect: Rect; iconRect: Rect;align: Integer;
    theIconSuite: Handle): BOOLEAN;    INLINE $303C, $0711, $ABC9;
FUNCTION IconIDToRgn(theRgn: RgnHandle; iconRect: Rect;align: Integer;
    iconID: INTEGER): OSErr;    INLINE $303C, $0913, $ABC9;
FUNCTION IconSuiteToRgn(theRgn: RgnHandle; iconRect: Rect;align: Integer;
    theIconSuite: Handle): OSErr;    INLINE $303C, $0914, $ABC9;
FUNCTION SetSuiteLabel(theSuite: Handle; theLabel: INTEGER): OSErr;
    INLINE $303C, $0316, $ABC9;
FUNCTION GetSuiteLabel(theSuite: Handle): INTEGER; INLINE $303C, $0217, $ABC9;
FUNCTION GetIconCacheData(theCache: Handle; VAR theData: Ptr): OSErr;
    INLINE $303C, $0419, $ABC9;
FUNCTION SetIconCacheData(theCache: Handle; theData: Ptr): OSErr;
    INLINE $303C, $041A, $ABC9;
FUNCTION GetIconCacheProc(theCache: Handle; VAR theProc: ProcPtr): OSErr;
    INLINE $303C, $041B, $ABC9;
FUNCTION SetIconCacheProc(theCache: Handle; theProc: procPtr): OSErr;
    INLINE $303C, $041C, $ABC9;
FUNCTION PlotCIconHandle(theRect: Rect; align: INTEGER; transform: INTEGER;
    theCIcon: CIconHandle): OSErr;    INLINE $303C, $061F, $ABC9;

/* C Glue */
pascal OSErr PlotIconID(const Rect *theRect, short align, short  transform, short theResID)
     = {0x303C, 0x0500, 0xABC9};
pascal OSErr NewIconSuite(Handle *theIconSuite) = {0x303C, 0x0207, 0xABC9};
pascal OSErr AddIconToSuite(Handle theIconData,Handle theSuite,ResType theType)= {0x303C, 0x0608, 0xABC9};
pascal OSErr GetIconFromSuite(Handle *theIconData,Handle theSuite,ResType theType)= {0x303C, 0x0609, 0xABC9};
pascal OSErr ForEachIconDo(Handle theSuite,short selector,ProcPtr action,void *yourDataPtr)
    = {0x303C, 0x080A, 0xABC9};
pascal OSErr GetIconSuite(Handle *theIconSuite,short theResID,short selector)= {0x303C, 0x0501, 0xABC9};
pascal OSErr DisposeIconSuite(Handle theIconSuite,Boolean disposeData)= {0x303C, 0x0302, 0xABC9};
pascal OSErr PlotIconSuite(const Rect *theRect,short align,short transform,Handle theIconSuite)
    = {0x303C, 0x0603, 0xABC9};
pascal OSErr MakeIconCache(Handle *theHandle,ProcPtr makeIcon,void *yourDataPtr)= {0x303C, 0x0604, 0xABC9};
pascal OSErr LoadIconCache(const Rect *theRect,short align,short transform,Handle theIconCache)
    = {0x303C, 0x0606, 0xABC9};
pascal OSErr GetLabel(short labelNumber,RGBColor *labelColor,Str255 labelString)= {0x303c, 0x050B, 0xABC9};
pascal Boolean PtInIconID(Point testPt,Rect *iconRect,short alignment,short iconID)= {0x303c, 0x060D, 0xABC9};
pascal Boolean PtInIconSuite(Point testPt,Rect *iconRect,short alignment,Handle theIconSuite)
    = {0x303c, 0x070E, 0xABC9};
pascal Boolean RectInIconID(Rect *testRect,Rect *iconRect,short alignment,short iconID)
    = {0x303c, 0x0610, 0xABC9};
pascal Boolean RectInIconSuite(Rect *testRect,Rect *iconRect,short alignment,Handle theIconSuite)
    = {0x303c, 0x0711, 0xABC9};
pascal OSErr IconIDToRgn(RgnHandle theRgn,Rect *iconRect,short alignment,short iconID)
    = {0x303c, 0x0613, 0xABC9};
pascal OSErr IconSuiteToRgn(RgnHandle theRgn,Rect *iconRect,short alignment,Handle theIconSuite)
    = {0x303c, 0x0714, 0xABC9};
pascal OSErr SetSuiteLabel(Handle theSuite, short theLabel)= {0x303C, 0x0316, 0xABC9};
pascal short GetSuiteLabel(Handle theSuite)= {0x303C, 0x0217, 0xABC9};
pascal OSErr GetIconCacheData(Handle theCache, void **theData)= {0x303C, 0x0419, 0xABC9};
pascal OSErr SetIconCacheData(Handle theCache, void *theData)= {0x303C, 0x041A, 0xABC9};
pascal OSErr GetIconCacheProc(Handle theCache, ProcPtr *theProc)= {0x303C, 0x041B, 0xABC9};
pascal OSErr SetIconCacheProc(Handle theCache, ProcPtr theProc)= {0x303C, 0x041C, 0xABC9};
pascal OSErr PlotSICNHandle(const Rect *theRect,short align,short transform,Handle theSICN)
    = {0x303C, 0x061E, 0xABC9};
pascal OSErr PlotCIconHandle(const Rect *theRect,short align,short transform,CIconHandle theCIcon)
    = {0x303C, 0x061F, 0xABC9};
pascal OSErr SetLabel(short labelNumber, const RGBColor *, ConstStr255Param)
    = {0x303C, 0x050C, 0xABC9};

===

+++++++++++++++++++++++++++

From: [e-mail] (Lloyd Lim)
Date: 21 May 92 06:06:28 GMT
Organization: U.C. Davis - Department of Computer Science

In article <[e-mail]> [e-mail] (Neal Trautman) writes:
>
>Tech Note #306, on the May Developer's CD, has the
>full details on System 7 Finder Icon Families and
>Icon Suites.
>
>[...]

I didn't get my CD yet - thanks for the preview.

The routines look really handy.  But no Gestalt selector?  Sigh.
Back to TrapAvailable(0xABC9) or an "informational" selector.
The old ways never die.

I think a big problem with Gestalt is that the need for selectors
is usually discovered after the fact.  That, and bugs like the
Resource Manager selector.

+++
Lloyd Lim               Internet: [e-mail]
224 Lysle Leach Hall    America Online: LimUnltd
U.C. Davis              AppleLink: LimUnltd
Davis, CA  95616        CompuServe: 72647,660

---------------------------

End of C.S.M.P. Digest
**********************